home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / TextArea.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  14.9 KB  |  506 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)TextArea.java    1.50 98/08/13
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.TextAreaPeer;
  17.  
  18. /**
  19.  * A <code>TextArea</code> object is a multi-line region
  20.  * that displays text. It can be set to allow editing or
  21.  * to be read-only.
  22.  * <p>
  23.  * The following image shows the appearance of a text area:
  24.  * <p>
  25.  * <img src="doc-files/TextArea-1.gif"
  26.  * ALIGN=center HSPACE=10 VSPACE=7>
  27.  * <p>
  28.  * This text area could be created by the following line of code:
  29.  * <p>
  30.  * <hr><blockquote><pre>
  31.  * new TextArea("Hello", 5, 40);
  32.  * </pre></blockquote><hr>
  33.  * <p>
  34.  * @version    1.50, 08/13/98
  35.  * @author     Sami Shaio
  36.  * @since       JDK1.0
  37.  */
  38. public class TextArea extends TextComponent {
  39.  
  40.     /**
  41.      * The number of rows in the TextArea.
  42.      * The number of Rows will determine the text area's
  43.      * height and the number of rows is not limited.
  44.      * Should be non negative.
  45.      *
  46.      * @serial
  47.      * @see getRows()
  48.      * @see setRows()
  49.      */
  50.     int    rows;
  51.  
  52.     /**
  53.      * The number of columns in the TextArea.
  54.      * The number of columns will determine the text area's
  55.      * width and the number of columns is not limited.
  56.      * Should be non negative.
  57.      *
  58.      * @serial
  59.      * @see getColumns()
  60.      * @see setColumns()
  61.      */
  62.     int    columns;
  63.  
  64.     private static final String base = "text";
  65.     private static int nameCounter = 0;
  66.  
  67.     /**
  68.      * Create and display both vertical and horizontal scrollbars.
  69.      * @since JDK1.1
  70.      */
  71.     public static final int SCROLLBARS_BOTH = 0;
  72.  
  73.     /**
  74.      * Create and display vertical scrollbar only.
  75.      * @since JDK1.1
  76.      */
  77.     public static final int SCROLLBARS_VERTICAL_ONLY = 1;
  78.  
  79.     /**
  80.      * Create and display horizontal scrollbar only.
  81.      * @since JDK1.1
  82.      */
  83.     public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
  84.  
  85.     /**
  86.      * Do not create or display any scrollbars for the text area.
  87.      * @since JDK1.1
  88.      */
  89.     public static final int SCROLLBARS_NONE = 3;
  90.  
  91.     /**
  92.      * Determines which scrollbars are created for the
  93.      * text area. It can be one of four values :
  94.      * <code>SCROLLBARS_BOTH</code> = both scrollbars.<BR>
  95.      * <code>SCROLLBARS_HORIZONTAL_ONLY</code> = Horizontal bar only.<BR>
  96.      * <code>SCROLLBARS_VERTICAL_ONLY</code> = Vertical bar only.<BR>
  97.      * <code>SCROLLBARS_NONE</code> = No scrollbars.<BR>
  98.      *
  99.      * @serial
  100.      * @see getScrollbarVisibility()
  101.      */
  102.     private int scrollbarVisibility;
  103.  
  104.     /*
  105.      * JDK 1.1 serialVersionUID
  106.      */
  107.      private static final long serialVersionUID = 3692302836626095722L;
  108.  
  109.     /**
  110.      * Initialize JNI field and method ids
  111.      */
  112.     private static native void initIDs();
  113.  
  114.     static {
  115.         /* ensure that the necessary native libraries are loaded */
  116.     Toolkit.loadLibraries();
  117.     initIDs();
  118.     }
  119.  
  120.     /**
  121.      * Constructs a new text area.
  122.      * This text area is created with both vertical and
  123.      * horizontal scroll bars.
  124.      */
  125.     public TextArea() {
  126.     this("", 0, 0, SCROLLBARS_BOTH);
  127.     }
  128.  
  129.     /**
  130.      * Constructs a new text area with the specified text.
  131.      * This text area is created with both vertical and
  132.      * horizontal scroll bars.
  133.      * @param     text the text to be displayed.
  134.      */
  135.     public TextArea(String text) {
  136.     this(text, 0, 0, SCROLLBARS_BOTH);
  137.     }
  138.  
  139.     /**
  140.      * Constructs a new empty text area with the specified number of
  141.      * rows and columns. The text area is created with scrollbar 
  142.      * visibility equal to {@link #SCROLLBARS_BOTH}, so both 
  143.      * vertical and horizontal scrollbars will be visible for this 
  144.      * text area.
  145.      * @param rows the number of rows
  146.      * @param columns the number of columns
  147.      */
  148.     public TextArea(int rows, int columns) {
  149.     this("", rows, columns, SCROLLBARS_BOTH);
  150.     }
  151.  
  152.     /**
  153.      * Constructs a new text area with the specified text,
  154.      * and with the specified number of rows and columns.
  155.      * This text area is created with both vertical and
  156.      * horizontal scroll bars.
  157.      * @param     text      the text to be displayed.
  158.      * @param     rows      the number of rows.
  159.      * @param     columns   the number of columns.
  160.      */
  161.     public TextArea(String text, int rows, int columns) {
  162.         this(text, rows, columns, SCROLLBARS_BOTH);
  163.     }
  164.  
  165.     /**
  166.      * Constructs a new text area with the specified text,
  167.      * and with the rows, columns, and scroll bar visibility
  168.      * as specified.
  169.      * <p>
  170.      * The <code>TextArea</code> class defines several constants
  171.      * that can be supplied as values for the
  172.      * <code>scrollbars</code> argument: 
  173.      * <code>SCROLLBARS_BOTH</code>, 
  174.      * <code>SCROLLBARS_VERTICAL_ONLY</code>, 
  175.      * <code>SCROLLBARS_HORIZONTAL_ONLY</code>, 
  176.      * and <code>SCROLLBARS_NONE</code>. Any other value for the 
  177.      * <code>scrollbars</code> argument is invalid and will result in 
  178.      * this text area being created with scrollbar visibility equal to 
  179.      * the default value of {@link #SCROLLBARS_BOTH}.
  180.      * @param     text the text to be displayed.
  181.      * @param     rows the number of rows.
  182.      * @param     columns the number of columns.
  183.      * @param     scrollbars a constant that determines what
  184.      *                scrollbars are created to view the text area.
  185.      * @since     JDK1.1
  186.      */
  187.     public TextArea(String text, int rows, int columns, int scrollbars) {
  188.     super(text);
  189.     this.rows = rows;
  190.     this.columns = columns;
  191.         if ((scrollbars >= SCROLLBARS_BOTH) && (scrollbars <= SCROLLBARS_NONE)) 
  192.                this.scrollbarVisibility = scrollbars;
  193.         else 
  194.             this.scrollbarVisibility = SCROLLBARS_BOTH;
  195.     }
  196.  
  197.     /**
  198.      * Construct a name for this component.  Called by getName() when the
  199.      * name is null.
  200.      */
  201.     String constructComponentName() {
  202.         synchronized (getClass()) {
  203.         return base + nameCounter++;
  204.     }
  205.     }
  206.  
  207.     /**
  208.      * Creates the TextArea's peer.  The peer allows us to modify
  209.      * the appearance of the TextArea without changing any of its
  210.      * functionality.
  211.      */
  212.     public void addNotify() {
  213.         synchronized (getTreeLock()) {
  214.         if (peer == null)
  215.             peer = getToolkit().createTextArea(this);
  216.         super.addNotify();
  217.     }
  218.     }
  219.  
  220.     /**
  221.      * Inserts the specified text at the specified position
  222.      * in this text area.
  223.      * @param      str the text to insert.
  224.      * @param      pos the position at which to insert.
  225.      * @see        java.awt.TextComponent#setText
  226.      * @see        java.awt.TextArea#replaceRange
  227.      * @see        java.awt.TextArea#append
  228.      * @since      JDK1.1
  229.      */
  230.     public void insert(String str, int pos) {
  231.         insertText(str, pos);
  232.     }
  233.  
  234.     /**
  235.      * @deprecated As of JDK version 1.1,
  236.      * replaced by <code>insert(String, int)</code>.
  237.      */
  238.     public synchronized void insertText(String str, int pos) {
  239.     TextAreaPeer peer = (TextAreaPeer)this.peer;
  240.     if (peer != null) {
  241.         peer.insertText(str, pos);
  242.     } else {
  243.         text = text.substring(0, pos) + str + text.substring(pos);
  244.     }
  245.     }
  246.  
  247.     /**
  248.      * Appends the given text to the text area's current text.
  249.      * @param     str the text to append.
  250.      * @see       java.awt.TextArea#insert
  251.      */
  252.     public void append(String str) {
  253.         appendText(str);
  254.     }
  255.  
  256.     /**
  257.      * @deprecated As of JDK version 1.1,
  258.      * replaced by <code>append(String)</code>.
  259.      */
  260.     public synchronized void appendText(String str) {
  261.     if (peer != null) {
  262.         insertText(str, getText().length());
  263.     } else {
  264.         text = text + str;
  265.     }
  266.     }
  267.  
  268.     /**
  269.      * Replaces text between the indicated start and end positions
  270.      * with the specified replacement text.
  271.      * @param     str      the text to use as the replacement.
  272.      * @param     start    the start position.
  273.      * @param     end      the end position.
  274.      * @see       java.awt.TextArea#insert
  275.      * @since     JDK1.1
  276.      */
  277.     public void replaceRange(String str, int start, int end) {
  278.     replaceText(str, start, end);
  279.     }
  280.  
  281.     /**
  282.      * @deprecated As of JDK version 1.1,
  283.      * replaced by <code>replaceRange(String, int, int)</code>.
  284.      */
  285.     public synchronized void replaceText(String str, int start, int end) {
  286.     TextAreaPeer peer = (TextAreaPeer)this.peer;
  287.     if (peer != null) {
  288.         peer.replaceText(str, start, end);
  289.     } else {
  290.         text = text.substring(0, start) + str + text.substring(end);
  291.     }
  292.     }
  293.  
  294.     /**
  295.      * Gets the number of rows in the text area.
  296.      * @return    the number of rows in the text area.
  297.      * @see       java.awt.TextArea#setRows
  298.      * @see       java.awt.TextArea#getColumns
  299.      * @since     JDK1
  300.      */
  301.     public int getRows() {
  302.     return rows;
  303.     }
  304.  
  305.     /**
  306.      * Sets the number of rows for this text area.
  307.      * @param       rows   the number of rows.
  308.      * @see         java.awt.TextArea#getRows
  309.      * @see         java.awt.TextArea#setColumns
  310.      * @exception   IllegalArgumentException if the value supplied
  311.      *                  for <code>rows</code> is less than zero.
  312.      * @since       JDK1.1
  313.      */
  314.     public void setRows(int rows) {
  315.     int oldVal = this.rows;
  316.     if (rows < 0) {
  317.         throw new IllegalArgumentException("rows less than zero.");
  318.     }
  319.     if (rows != oldVal) {
  320.         this.rows = rows;
  321.         invalidate();
  322.     }
  323.     }
  324.  
  325.     /**
  326.      * Gets the number of columns in this text area.
  327.      * @return    the number of columns in the text area.
  328.      * @see       java.awt.TextArea#setColumns
  329.      * @see       java.awt.TextArea#getRows
  330.      */
  331.     public int getColumns() {
  332.     return columns;
  333.     }
  334.  
  335.     /**
  336.      * Sets the number of columns for this text area.
  337.      * @param       columns   the number of columns.
  338.      * @see         java.awt.TextArea#getColumns
  339.      * @see         java.awt.TextArea#setRows
  340.      * @exception   IllegalArgumentException if the value supplied
  341.      *                  for <code>columns</code> is less than zero.
  342.      * @since       JDK1.1
  343.      */
  344.     public void setColumns(int columns) {
  345.     int oldVal = this.columns;
  346.     if (columns < 0) {
  347.         throw new IllegalArgumentException("columns less than zero.");
  348.     }
  349.     if (columns != oldVal) {
  350.         this.columns = columns;
  351.         invalidate();
  352.     }
  353.     }
  354.  
  355.     /**
  356.      * Gets an enumerated value that indicates which scroll bars
  357.      * the text area uses.
  358.      * <p>
  359.      * The <code>TextArea</code> class defines four integer constants
  360.      * that are used to specify which scroll bars are available.
  361.      * <code>TextArea</code> has one constructor that gives the
  362.      * application discretion over scroll bars.
  363.      * @return     an integer that indicates which scroll bars are used.
  364.      * @see        java.awt.TextArea#SCROLLBARS_BOTH
  365.      * @see        java.awt.TextArea#SCROLLBARS_VERTICAL_ONLY
  366.      * @see        java.awt.TextArea#SCROLLBARS_HORIZONTAL_ONLY
  367.      * @see        java.awt.TextArea#SCROLLBARS_NONE
  368.      * @see        java.awt.TextArea#TextArea(java.lang.String, int, int, int)
  369.      * @since      JDK1.1
  370.      */
  371.     public int getScrollbarVisibility() {
  372.         return scrollbarVisibility;
  373.     }
  374.  
  375.  
  376.     /**
  377.      * Determines the preferred size of a text area with the specified
  378.      * number of rows and columns.
  379.      * @param     rows   the number of rows.
  380.      * @param     cols   the number of columns.
  381.      * @return    the preferred dimensions required to display
  382.      *                       the text area with the specified
  383.      *                       number of rows and columns.
  384.      * @see       java.awt.Component#getPreferredSize
  385.      * @since     JDK1.1
  386.      */
  387.     public Dimension getPreferredSize(int rows, int columns) {
  388.         return preferredSize(rows, columns);
  389.     }
  390.  
  391.     /**
  392.      * @deprecated As of JDK version 1.1,
  393.      * replaced by <code>getPreferredSize(int, int)</code>.
  394.      */
  395.     public Dimension preferredSize(int rows, int columns) {
  396.         synchronized (getTreeLock()) {
  397.         TextAreaPeer peer = (TextAreaPeer)this.peer;
  398.         return (peer != null) ? 
  399.                peer.preferredSize(rows, columns) :
  400.                super.preferredSize();
  401.         }
  402.     }
  403.  
  404.     /**
  405.      * Determines the preferred size of this text area.
  406.      * @return    the preferred dimensions needed for this text area.
  407.      * @see       java.awt.Component#getPreferredSize
  408.      * @since     JDK1.1
  409.      */
  410.     public Dimension getPreferredSize() {
  411.     return preferredSize();
  412.     }
  413.  
  414.     /**
  415.      * @deprecated As of JDK version 1.1,
  416.      * replaced by <code>getPreferredSize()</code>.
  417.      */
  418.     public Dimension preferredSize() {
  419.         synchronized (getTreeLock()) {
  420.         return ((rows > 0) && (columns > 0)) ? 
  421.             preferredSize(rows, columns) :
  422.             super.preferredSize();
  423.         }
  424.     }
  425.  
  426.     /**
  427.      * Determines the minimum size of a text area with the specified
  428.      * number of rows and columns.
  429.      * @param     rows   the number of rows.
  430.      * @param     cols   the number of columns.
  431.      * @return    the minimum dimensions required to display
  432.      *                       the text area with the specified
  433.      *                       number of rows and columns.
  434.      * @see       java.awt.Component#getMinimumSize
  435.      * @since     JDK1.1
  436.      */
  437.     public Dimension getMinimumSize(int rows, int columns) {
  438.         return minimumSize(rows, columns);
  439.     }
  440.  
  441.     /**
  442.      * @deprecated As of JDK version 1.1,
  443.      * replaced by <code>getMinimumSize(int, int)</code>.
  444.      */
  445.     public Dimension minimumSize(int rows, int columns) {
  446.         synchronized (getTreeLock()) {
  447.         TextAreaPeer peer = (TextAreaPeer)this.peer;
  448.         return (peer != null) ? 
  449.                peer.minimumSize(rows, columns) :
  450.                super.minimumSize();
  451.         }
  452.     }
  453.  
  454.     /**
  455.      * Determines the minimum size of this text area.
  456.      * @return    the preferred dimensions needed for this text area.
  457.      * @see       java.awt.Component#getPreferredSize
  458.      * @since     JDK1.1
  459.      */
  460.     public Dimension getMinimumSize() {
  461.     return minimumSize();
  462.     }
  463.  
  464.     /**
  465.      * @deprecated As of JDK version 1.1,
  466.      * replaced by <code>getMinimumSize()</code>.
  467.      */
  468.     public Dimension minimumSize() {
  469.         synchronized (getTreeLock()) {
  470.         return ((rows > 0) && (columns > 0)) ? 
  471.             minimumSize(rows, columns) :
  472.             super.minimumSize();
  473.         }
  474.     }
  475.  
  476.     /**
  477.      * Returns the parameter string representing the state of
  478.      * this text area. This string is useful for debugging.
  479.      * @return      the parameter string of this text area.
  480.      */
  481.     protected String paramString() {
  482.     String sbVisStr;
  483.     switch (scrollbarVisibility) {
  484.         case SCROLLBARS_BOTH:
  485.         sbVisStr = "both";
  486.         break;
  487.         case SCROLLBARS_VERTICAL_ONLY:
  488.         sbVisStr = "vertical-only";
  489.         break;
  490.         case SCROLLBARS_HORIZONTAL_ONLY:
  491.         sbVisStr = "horizontal-only";
  492.         break;
  493.         case SCROLLBARS_NONE:
  494.         sbVisStr = "none";
  495.         break;
  496.         default:
  497.         sbVisStr = "invalid display policy";
  498.     }
  499.  
  500.     return super.paramString() + ",rows=" + rows +
  501.         ",columns=" + columns +
  502.       ", scrollbarVisibility=" + sbVisStr;
  503.     }
  504.  
  505. }
  506.